---

7. Target Settings for Java

CodeWarrior target settings are options you can specify to determine various aspects of your project's behavior, such as how it compiles and links. Choosing the right settings can significantly improve the size and speed of your final code.

Target settings are organized into panels that you can display in CodeWarrior's target settings window (Figure 7.1). Different settings panels control various properties of the project.

This chapter discusses only those project settings panels that relate specifically to Java programming:

• Target Settings
• Java Target
• Java Command Line
• Java Language
• FTP Post Linker
• Java Mac OS Post Linker
• Java Output
• JavaDoc

See the IDE User Guide, C Compilers Reference, and Pascal Compilers Reference for information about other settings panels available in the Target Settings Dialog.

The Target Settings panel is the most critical panel in CodeWarrior. This is the panel where you pick the operating system and/or microprocessor your project is to run on.

The Target Settings panel, shown in Figure 7.2, allows you to set the name of your target, as well as which linker and post linker plugins to use for the target. When you select a linker, you are specifying the target operating system and/or chip. The other panels available in this dialog box will change to reflect your choice.

Because the linker choice affects the visibility of other related panels, you must set which linkers your project will use before you can specify other target-specific options like compiler and linker settings.

The items in this panel are:

Target Name	Post-linker
Linker	Output Directory
Pre-linker	Save project entries using relative paths

Use the Target Name field to set or change the name of a build target. When you use the Targets view in the Project window, you will be able to see this name.

This is not the name of your final output file. It is the name you assign to the build target for your project file to use. The name of the final output file is set in the Java Output panel.

Choose a linker from the items listed in the Linker pop-up menu.

Some targets have pre-linkers that perform additional work (such as a data format conversion) before linking. There is one pre-linker for Java: the JavaDoc Pre-Linker.

"JavaDoc."

Some targets have post linkers that perform additional work (such as a data format conversion) on the final executable. The post linkers available for your use are described in Table 7.1:

FTP Post Linker	"FTP Post Linker"
Java Mac OS Post Linker	"Java Mac OS Post Linker"
JCommand Line	"Java Command Line"

This is the directory where your final linked output file will be placed. The default location is the directory that contains your project file. Click the Choose button to specify another directory.

When enabled, this setting allows the IDE to distinguish between files with the same names but in different directories. If you do not have files with the same name in your project, you can leave this option off.

The settings you can specify on the Java Target panel depend on whether you are creating an applet, a library, or jar file.

The settings in this panel change based on which option is selected in the Target Type pop-up menu. This section contains the following sections:

• Applet
• Application
• Library

If the Target Type pop-up menu is set to Applet as shown in Figure 7.3, CodeWarrior will create a Java applet from your project when you build it.

On Windows, this area of the panel contains a pop-up menu as shown in Figure 7.4. The menu contains an item for each applet viewer found on your computer, and an Other item, which enables the Choose button.

On Mac OS and Solaris, this area of the panel conatins a text field which displays the currently-selected applet viewer (Figure 7.5). Currently, Sun's appletviewer program is the only supported applet viewer on Solaris.

To use an applet viewer other than those listed by default, click the Choose button. CodeWarrior displays an open file dialog box, allowing you to locate and select another applet viewer.

CodeWarrior uses the JDK 1.1.6 Virtual Machine by default. The items in this pop-up menu reflect the contents of the (jdk_options) folder, which resides in the JavaSupport folder of CodeWarrior. The IDE scans this folder when building this pop-up menu and adds to the menu any files it finds in the folder. CodeWarrior includes jdk1.1.6 and jdk1.2 by default.

The files in the (jdk_options) folder are expected to be soft links to the root level of the JDK package in question. Items can be added to this menu to allow you to run your applets with newer versions of JDKs as they become available. The JDK package itself must reside in the JavaSupport folder. And a soft link to that package must be placed into the (jdk_options) folder.

For example, to add a menu item for JDK 1.3, you would issue the following commands in a terminal:

cd /usr/local/Metrowerks/CodeWarrior3.3/JavaSupport/

ln -s "(jdk1.3)" "/(jdk_options)/jdk1.3

This creates a soft link in the (jdk_options) folder which points to the (jdk1.3) folder which resides in the JavaSupport folder. The next time the menu is built, it will contain the new link.

If the Target Type pop-up menu is set to Application as shown in Figure 7.6, CodeWarrior will create a Java application from your project when you build it.

The VM Arguments field is only available on Solaris. It allows you to specify the options you would normally specify in the java command line. When you launch your Java application from within the CodeWarrior IDE, these arguments will be bpassed to the VM. Multiple arguments must be delimited by spaces.

The Main Class field identifies the name of the class containing the main() method in a Java application. Enter only the name of the class. Do not use the .class extension. You are specifying the class itself, not the file.

CodeWarrior passes this name to the VM running the application so it can begin execution. This field must have a value in order to run a Java application.

Enter any arguments you wish to pass to the main() method when the application launches. A series of arguments must be delimited by spaces.

The Windows-hosted CodeWarrior IDE uses the Windows VM by default. You may also use Suns JDK VM.

The Solaris-hosted CodeWarrior IDE uses the JDK 1.1.6 Virtual Machine by default. The items in this pop-up menu reflect the contents of the (jdk_options) folder, which resides in the JavaSupport folder of CodeWarrior. The IDE scans this folder when building this pop-up menu and adds to the menu any files it finds in the folder. CodeWarrior includes jdk1.1.6 and jdk1.2 by default.

The files in the (jdk_options) folder are expected to be soft links to the root level of the JDK package in question. Items can be added to this menu to allow you to run your applets with newer versions of JDKs as they become available. The JDK package itself must reside in the JavaSupport folder. And a soft link to that package must be placed into the (jdk_options) folder.

For example, to add a menu item for JDK 1.3, you would issue the following commands in a terminal:

cd /usr/local/Metrowerks/CodeWarrior3.3/JavaSupport/

ln -s "(jdk1.3)" "/(jdk_options)/jdk1.3

This creates a soft link in the (jdk_options) folder which points to the (jdk1.3) folder which resides in the JavaSupport folder. The next time the menu is built, it will contain the new link.

The Working Directory field is optional.The default working directory is the directory where the VM resides. Set this field if you require a different working directory.

If the Target Type pop-up menu is set to Library as in Figure 7.7, CodeWarrior creates a Java library from your project.

The Java Command Line panel (Figure 7.8) allows you to launch a Java application after your project is successfully built to do further processing of your project output.

For instance, you may use it to launch RMIC, a Java utility that takes .class files and generates stub classes. The java linker would generate the .class files. Then the RMI compiler (RMIC) would take those class files and generate stub class files for use with RMI. Similar utilities can be found in the Classes.zip Java library file.

This panel contains the following items:

Put the name of the main class of the application you want to be invoked into this field. Once your project is successfully built, the linker will run the application.

Put any arguments to be sent to the application into this field.

This linker adds paths to all zips and jars in the project to the VM classpath. It also adds the project output to the classpath.

The Java Language panel (Figure 7.9) contains project settings related to code generation for the Java platform.

The options in this panel are:

Generate Profiler Information	Emit Headers for Native Methods
Emit Dependency Map	Use Strict Java Filenames
Inlining Enabled	Use Strict Source/Package Hierarchy
Runtime Checks	Browser Package Name Filter
Warn About Deprecated Methods

This option adds timing information to your Java methods. You can only profile Java applications. To use this option, you must include Profiler.zip in your project. When your Java code finishes executing, a new file is created with the timing data. You can view this file with the MW Profiler application on Mac OS.

This option is similar to generating a link map in other languages such as C and C++. When enabled, a new file is created in the same directory as your project file called sourcefile.JMAP, where sourcefile is the name of your .java source file. The JMAP file lists all the class dependencies for each class in the file.

For example, the statement import java.* is common in Java source code. The dependency map tells you the exact class dependencies. So the statement import java.* may become:

import java.applet.Applet;

import java.applet.AppletContext;

You can then use these statements in your Java source files instead of importing everything. This makes things cleaner, faster and more portable to other Java compilers.

Allows inlining of smaller methods where appropriate.

This option only effects the J2N (Java To Native) compiler, which is currently in pre-release stages.

When this option is enabled, the J2N compiler generates runtime checks required by Java, such as null pointers or array lengths. This is useful for debugging; but is probably not neccessary in the final application.

When this option is disabled, more optimized and efficient code is generated; but no checks are performed.

Gives warning messages if you are using any depreciated methods. This allows you to find references to depreciated methods in your code so that you can update your code to the newer methods.

Emits headers for any native methods for every class in your project. When this option is enabled, the Emit pop-up menu appears allowing you to choose between JNI Headers and Sun VM Headers. JNI is the newest and preferred method. However, for compatibility reasons, you may wish to choose the Sun VM Headers option.

The other options that can be used in conjunction with Emit Headers for Native Methods are Generate Comments in Headers and Generate Headers for All Classes.

Generate Comments in Headers moves comments from the java sources files to the native headers.

Generate Headers for All Classes generates the headers in a tree (like sun/tools/java/Identifier.h) instead of mangled with the package (like sun_tools_java_Identifier.h)

Forces strict class names based on the Java source file names. For example, if you have a java source file called FooBar.Java, the compiler expects to find a class called FooBar.class in this file. No other class can be in this file.

Forces strict adherence to source and package hierarchy paths. For example, if you have the following package:

Foo\bar\seam

The compiler expects a to find file seam.java in a directory called "bar" which is in a directory called "Foo."

This option is only available when Use Strict Java Filenames is enabled.

Accepts a semicolon delimited list of names that you do not want to show up in the class browser. If you type in: java.io; java.lang, the browser will only display File, Object and reflect.Method for classes like java.io.File, java.lang.Object, and java.lang.reflect.Method.

You can also use wildcards like java.*, in which case the browser will strip off the entire package for any class starting with "java."

Finally, you can also type in "*" (no quotes), in which case the browser strips all packages off everything.

The FTP Post Linker panel allows you to move a folder containing your completed Java binary and any associated files to a server to be accessed through the World Wide Web.

The items in this panel are:

Host Address	Folder to Upload
User Name	Binary Transfer
Password	Generate Log
Remote Directory

The host address of the server you want to upload your Java files to.

Your user ID on the host server.

Your password on the host server.

Directory you want to upload the Java files to on the host system. You must have access privileges for this directory.

The full path to the folder on your local hard drive containing the files to upload. There is no way to specify that individual files be uploaded, so the linker will transfer the entire contents of the folder specified here. Make sure you do not have any files that you do not want transferred in this folder.

Transfer the files to the host system using Binary mode instead of ASCII. It is recommended this option always be turned on to avoid any transfer problems.

Generates a text log file of the transfer. Any errors or problems are recorded in this file.

The settings in the Java Mac OS Settings panel control the operation of the Java Mac OS Post Linker. This post linker determines how Mac OS Java applications are packaged.

The Mac OS Java Output Type pop-up menu can be set to one of the following settings:

• JBindery
• Mac OS Zip

When the JBindery output type is selected, the panel appears as in Figure 7.11. JBindery is an application that you use to package or execute Java applications on the Mac OS platform.The settings contained in this panel allow you to control how JBindery builds your application.

The Java Mac OS Post Linker will launch JBindery using the follwing settings.

This pop-up menu allows you to redirect stdout. You can either redirect stdout to a message window generated by JBindery, or you can instruct JBindery to ignore stdout altogether.

This pop-up menu allows you to redirect stdin. You can either redirect stdin to a message window generated by JBindery, or you can instruct JBindery to ignore stdin altogether.

Check this checkbox to enable method profiling.

This checkbox determines whether the size box should appear within the corner of the actual window. If the size boxes intrude, any Abstract Window Toolkit components that would normally appear under the size box are not drawn. If you do not check this box, an extra strip of empty space is added to the bottom of the window to accomodate the size box.

If this checkbox is checked, the zip file will be merged into the final application when you build your project.

Check this checkbox if you want the code verifier to check local Java bytecodes before execution. If this checkbox is not selected, JBindery will still automatically check any bytecodes obtained from a remote source (such as over a network).

If you would like your application to use an HTTP proxy server, check this checkbox, and supply the name and port ID of the proxy server in the corresponding edit fields.

Check this checkbox if you would like your application to use an FTP proxy server. Supply the name and port ID of the proxy server in the corresponding edit fields.

This option specifies whether you want to use a firewall proxy. When this checkbox is checked, the Java application uses the firewall proxy server specified in the name and port edit fields when accessing servers outside the security firewall.

This edit field lets you specify the creator of your final Java application.

This edit field lets you specify a creator for your Java application. This unique string identifies the application and any documents that the application may create. If you plan to publically distribute your application, you must register its creator name with Apple through Developer Technical Support to avoid collisions between names used by different developers.

You can register a creator online or view currently registered creators at the following Web site:

http://devworld.apple.com/dev/cftype/main.html

These two edit fields let you specify the amount of memory to use when executing this Java program. Mac OS Runtime for Java uses temporary memory for most allocations (the Java virtual machine and so on) so an application heap of 512K is usually sufficient.

When the Mac OS Zip menu item is selected, the panel appears as in Figure 7.12. Previous versions of the Java Linker copied Mac OS resources into the output zip file. This was handy for adding 'vers' resources to your zip file, for example. This option allows you to do the same thing.

Create `old' Mac OS resources - The Java Linker used to create certain resources in the output zip file that were used to assist in building standalone applications. These resources are no longer needed by CodeWarrior, and are no longer written. However, with JBindery in MRJ SDK 2.0.1, if you drop jar/zip files containing these resources onto JBindery, it will still parse out the main class name and the main arguments and use them. This option is available for this reason.

Create New File - If this checkbox is checked, resources will be added to a copy of the Java Linker output file, rather than the original output file. Otherwise, resources will be merged into the Java Linker output file. Supply the name of the new file in the Output filename edit field.

The settings on the Java Output panel control the operation of the CodeWarrior linker for Java. The Output Type can be:

• Class Folder
• Jar File
• Application

If you choose Class Folder from the Output Type pop-up menu, the IDE will create a new folder with the name you specify in the Name field. Every class in your project will be placed in this folder.

The Mac OS has a 31 character maximum for filenames. The Filename Truncation menu controls where the IDE will remove characters of the final class file name if it is too large. You can choose From Front, From Middle, or From End.

Delete class files from output directory before linking simply removes all class files in the target directory before linking your code. This is useful if you recompile your source often as it makes sure no old code exists in the target folder.

A Jar file is a Java Archive file. The Jar File option (Figure 7.14) allows you to control how the Jar file is created. Choose Compress to create a compressed Jar file. Choose Generate Manifest to have manifest information added to the Jar file.

The Type and Creator fields only appear in the Mac OS hosted version of CodeWarrior. These fields allow you to change the default application used to open them if you double-click on the file on the Mac OS. The default settings open the Jar file in Class Wrangler.

"Class Wrangler for Mac OS."

Choose Application from the Output Type popup menu to create a Java application (Figure 7.15).

Choose Compress to create a compressed Jar file. Choose Generate Manifest to create manifest information in the file.

When the Console Application option is enabled, the DOS prompt window will display when you launch the application. System.out, System.err and System.in will use the console's io streams for standard input/output. In other words, the application is a CUI Windows application. When this option is disabled, the console window does not display because the application is built as a GUI Windows application. The user will not be able to see standard I/O unless they pipe it somewhere else.

The JavaDoc panel (Figure 7.16) controls how JavaDoc creates documentation for your Java source.

Three ignore options: Ignore @version comments, Ignore @deprecated comments, and Ignore @author comments tell JavaDoc to omit comments with these "tags" from the final output when enabled.

Tells JavaDoc to generate filenames shortened to 31 characters to create cross-platform friendly HTML documents. This option is not available on the Mac OS version of CodeWarrior.

Generate index tells JavaDoc to create index information in the final output. Sometimes, the index can be very large. Turn this option off if you do not want index information generated for your project.

Generate hierarchy tells JavaDoc to generate class hierarchy information. Turn this option off if you do not want hierarchy information created.

Instead of only outputting the HTML files for a project to a flat folder hierarchy with extremely long filenames, the JavaDoc Pre-Linker has the option of putting the files into a package-based folder hierarchy. The actual file names are only the class name.

Use this option to set the creator code for HTML files to your favorite HTML browser. This option is only available on the Mac OS hosted version of CodeWarrior.

The Scope pop-up menu controls which classes will be included in the documentation. Choices include:

• public
• protected and public
• protected, public and package
• all

The two encoding options: Source file encoding and Output encoding are for internationalization of your JavaDoc files. For example, the Java source files can be in Arabic and output in English.

Encoding numbers are used in each field. JavaDoc converts the number in the source field to Unicode, and then from Unicode to the value specified in the output field. Leave these fields blank to use the default ISO Latin (9859-1) encoding.

For more information on encoding, see:

http://java.sun.com/products/jdk/1.1/intl/html/intlspec.doc7.html

This option adds links to the main Java API docs where appropriate in your code. The default link is on the Web. If you have a dial-up connection, you might prefer to have the API docs somewhere on your local machine. This way, you can specify the URL to be something like file://my_drive/jdk_docs/. You can also specify a relative URL.